Skip to main content

26P-AD-00001: Document 層プラットフォームとして Docusaurus + MDX を採用

改訂履歴​

版日付作成者章番号／章タイトル改訂内容／理由
v1.0.02026/05/10--初版作成

コンテキスト​

sddp の Document 層をどのプラットフォームで構築するかを決定する必要があった。

Document 層に求める要件は以下の通り：

  • AI（Claude Code 等）がソースコードと同じコンテキストで設計書を読めること
  • 人間にとっての読みやすさ（静的テキスト以上の表現力）
  • 無料・OSS・セルフホスト可能であること
  • 技術者が Git ワークフローで管理できること
  • 機密情報を置かない前提で設計知識のみを管理すること

また、以下の制約も考慮した：

  • 個人開発者・小規模チームが対象であり、高額なライセンス費用は許容できない
  • 非技術者が書く必要はない（Document 層は技術者が管理する）
  • デプロイ形態はプロジェクトの規模・セキュリティ要件に応じて選択できること

決定​

Document 層のプラットフォームとして Docusaurus + MDX を採用する。

具体的には：

  1. ドキュメントは .mdx 形式で記述し、Docusaurus でレンダリングする
  2. MDX の JSX/TSX 埋め込み機能を活用し、プログラマブルなドキュメントを実現する
  3. GitHub リポジトリ上で管理し、AI がソースコードと設計書を同じコンテキストで読める構造とする
  4. 機密情報（クライアント原本・契約・認証情報）は置かない。設計知識のみを蒸留して置く
  5. デプロイ形態は任意とし、プロジェクトの要件に応じて選択する

検討した選択肢​

A案: Plain Markdown / AsciiDoc（デプロイなし）​

  • ファイルをそのまま管理し、Docusaurus は使わない
  • 利点: 設定ゼロ、最大のシンプルさ、AI はファイルを直接読める
  • 欠点: 人間の読みやすさが低い、インタラクティブな表現ができない、チーム共有時に不便

B案（採用）: Docusaurus + MDX​

  • Docusaurus を Document 層のレンダラーとして採用し、MDX でコンテンツを管理する
  • 利点: プログラマブルドキュメント（JSX/TSX）、AI がコードと同時に読める、無料・OSS、Git 管理、デプロイ形態の柔軟性
  • 欠点: 非技術者は書けない、Node.js 環境が必要

C案: Confluence​

  • Atlassian Confluence をドキュメント管理基盤として採用する
  • 利点: 非技術者も WYSIWYG で書ける、実績豊富
  • 欠点: セルフホスト版（Data Center）は高額、MCP 設定なしでは AI が直接読めない、MDX のようなプログラマブル表現は不可

D案: GitBook​

  • GitBook をドキュメント管理基盤として採用する
  • 利点: UI が洗練されている、Markdown で書ける
  • 欠点: チーム利用は有料、プログラマブルドキュメントの表現力が低い、OSS ではない

機密情報の取り扱い方針​

Document 層に置くのは設計知識のみとする。以下は置かない：

置かないもの管理場所
クライアントからの原本仕様書・契約書Google Drive 等の社内ストレージ
環境変数・認証情報Secret Manager / .env（.gitignore）
個人情報を含む仕様書社内 DMS

クライアント原本から設計判断・要件の要点を抽出し、sddp Document 層に「設計知識として蒸留」して記録する。

デプロイ形態​

デプロイは任意であり、プロジェクトの要件に応じて選択する。AI との連携はデプロイなしでも成立する（Claude Code がファイルを直接読む）。

形態向き認証
ローカルのみ（npm start）個人開発不要
Tailscale 経由個人・身内の少人数デバイス単位
Cloudflare Pages + Access小規模チームGoogle/GitHub アカウント
Confluence からリンク大企業（Confluence 導入済み）Confluence の権限管理に委譲

影響​

変更が必要な文書​

開発ワークフローへの影響​

  • ドキュメントは .mdx で記述する（.md も使用可能だが、JSX を使う場合は .mdx）
  • docs/ ディレクトリで npm start を実行してローカルプレビューする
  • JSX コンポーネントは各 .mdx ファイル内に export const で定義するか、src/components/ に切り出す

参考資料​